string.prototype.matchall

What is string.prototype.matchall?

The string.prototype.matchall npm package is a polyfill for the `String.prototype.matchAll` method, which returns an iterator of all results matching a string against a regular expression, including capturing groups. This package is particularly useful for environments that do not yet support the `matchAll` method natively.

What are string.prototype.matchall's main functionalities?

Matching all occurrences of a pattern

This feature allows you to find all occurrences of the pattern `/test/g` in the string `"test1test2"`. It returns an iterator that contains all matches.

"test1test2".matchAll(/test/g)

Capturing groups in matches

This demonstrates how to use capturing groups with `matchAll`. The regular expression `/(te)(st\d)/g` includes two capturing groups that match parts of the string. The result is an iterator of matches, where each match includes the full matched text and the text matched by each capturing group.

"test1test2".matchAll(/(te)(st\d)/g)

Other packages similar to string.prototype.matchall

xregexp

XRegExp provides augmented, extensible regular expressions. You can use it for more complex matching and replacing operations than what's possible with native JavaScript RegExp. It includes support for additional syntax and flags. While it offers more features overall, it doesn't specifically focus on the `matchAll` functionality but can achieve similar results with its APIs.

regexp-match-indices

This package offers a polyfill for the `RegExp.prototype.exec` method to include match indices in the result objects. It's similar to `string.prototype.matchall` in that it enhances the capabilities of regular expressions in JavaScript, but it focuses on providing match position information rather than iterating over all matches.

README

string.prototype.matchall

ES2020 spec-compliant shim for String.prototype.matchAll. Invoke its "shim" method to shim String.prototype.matchAll if it is unavailable or noncompliant.

This package implements the es-shim API interface. It works in an ES3-supported environment, and complies with the spec.

Most common usage:

const assert = require('assert');
const matchAll = require('string.prototype.matchall');

const str = 'aabc';
const nonRegexStr = 'ab';
const globalRegex = /[ac]/g;
const nonGlobalRegex = /[bc]/i;

// non-regex arguments are coerced into a global regex
assert.deepEqual(
	[...matchAll(str, nonRegexStr)],
	[...matchAll(str, new RegExp(nonRegexStr, 'g'))]
);

assert.deepEqual([...matchAll(str, globalRegex)], [
	Object.assign(['a'], { index: 0, input: str, groups: undefined }),
	Object.assign(['a'], { index: 1, input: str, groups: undefined }),
	Object.assign(['c'], { index: 3, input: str, groups: undefined }),
]);

assert.throws(() => matchAll(str, nonGlobalRegex)); // non-global regexes throw

matchAll.shim(); // will be a no-op if not needed

// non-regex arguments are coerced into a global regex
assert.deepEqual(
	[...str.matchAll(nonRegexStr)],
	[...str.matchAll(new RegExp(nonRegexStr, 'g'))]
);

assert.deepEqual([...str.matchAll(globalRegex)], [
	Object.assign(['a'], { index: 0, input: str, groups: undefined }),
	Object.assign(['a'], { index: 1, input: str, groups: undefined }),
	Object.assign(['c'], { index: 3, input: str, groups: undefined }),
]);

assert.throws(() => matchAll(str, nonGlobalRegex)); // non-global regexes throw

Tests

Simply clone the repo, npm install, and run npm test

Changelog

v4.0.11 - 2024-03-19

Commits

• [Deps] update call-bind, define-properties, es-abstract, get-intrinsic, internal-slot, regexp.prototype.flags, set-function-name, side-channel 628a475
• [Dev Deps] update aud, mock-property, npmignore, object-inspect, object.assign, object.entries, tape 21b67f2
• [actions] remove redundant finisher 27e8b80
• [Robustness] better cache original RegExp 92e9c59
• [Robustness] use es-errors f6de643
• [Refactor] use gopd 965a357
• [Refactor] use es-object-atoms where possible 1d15123
• [meta] add missing engines.node 04bdb31